JLC Docs
PIG
AI
PIG
AI

Claude Code 构建企业级项目

当企业项目包含前端、后端、文档等多个独立模块时，直接在单一模块目录使用 Claude Code 会遇到问题：

  • 上下文割裂 - Claude 不知道当前模块与其他模块的依赖关系
  • 技术栈混淆 - 前端 Vue 规范和后端 Java 规范混在一起，容易产生错误建议
  • 团队协作困难 - 不同子模块由不同团队维护，缺乏统一的入口说明

通过 Git Submodule + 分层 CLAUDE.md 结构可以解决这些问题：

  • 根目录 CLAUDE.md - 全局视角，描述模块间关系、整体架构、跨模块开发规范
  • 子模块 CLAUDE.md - 局部视角，描述该模块的技术栈、代码规范、构建命令

目录结构

project/                     # 父仓库根目录
    ├── docs            # 项目文档、需求设计文档，包括测试，以及各种文档
    │   ├── AGENTS.md        
    │   └── CLAUDE.md        
    ├── pigx                # Java 后端服务（Spring Cloud）
    │   ├── AGENTS.md        
    │   └── CLAUDE.md        
    ├── pigx-ai-app         # APP 应用
    │   ├── AGENTS.md       
    │   └── CLAUDE.md        
    ├── pigx-ui         # 前端应用（Vue3 + TypeScript）
    │   └── CLAUDE.md        
    ├── AGENTS.md            # 全局 Agent 指令（Codex 兼容）
    └── CLAUDE.md            # 项目整体上下文（入口）

CLAUDE.md 编写规范

核心原则

CLAUDE.md 是唯一默认加载到每次对话的文件，内容越精简，Claude 的执行效果越好：

原则说明
少即是多控制在 300 行以内更佳
普遍适用只写对所有任务都适用的内容
具体明确避免模糊指令如「代码要规范」
不替代 Linter代码格式交给工具SKILL，不写进 CLAUDE.md

WHY-WHAT-HOW 框架

# 项目名称（WHAT）

一句话说明项目是什么。

## 技术栈（WHAT）

- 后端：Java 17 + Spring Boot 3.x
- 前端：Vue3 + TypeScript

## 项目结构（WHAT）

- `src/main/` - 业务代码
- `src/test/` - 测试代码

## 常用命令（HOW）

- 启动：`mvn spring-boot:run`
- 测试：`mvn test`

## 开发约定（WHY + HOW）

- Controller 不写业务逻辑（因为要保持单一职责）
- 使用 R 类统一返回格式（因为前端需要统一解析）

渐进式披露

将详细文档拆分到独立文件，CLAUDE.md 只做索引：

## 详细文档

- 构建指南：@docs/building.md
- 测试规范：@docs/testing.md
- 部署流程：@docs/deployment.md
避免自动生成
不要使用 /init 自动生成后直接使用，CLAUDE.md 应该精心编写。

根目录 CLAUDE.md 编写

根目录的 CLAUDE.md 负责全局上下文，包含三个核心部分：

# PIG Cloud 企业级微服务平台

基于 Spring Cloud + Vue3 的企业级微服务解决方案。

## 模块概览

...

## 跨模块开发规范

- 后端 API 变更必须同步更新 `pig-docs/` 中的接口文档
- 前端调用新接口前，确认后端已合并到 dev 分支

## 模块详细说明

各模块的技术细节、构建命令、代码规范请参考对应目录下的 CLAUDE.md：

- 后端开发：参考 `pigx/CLAUDE.md`
- 前端开发：参考 `pigx-ui-pro/CLAUDE.md`
- AI 开发：参考 `pigx-ai-app/CLAUDE.md`
- 文档编写：参考 `pig-docs/CLAUDE.md`

子模块 CLAUDE.md 编写

子模块的 CLAUDE.md 专注于该模块的具体规范。以后端模块为例：

# PIGX 后端服务

Spring Cloud 微服务架构，提供用户、权限、业务等核心能力。

## 技术栈

- Java 17 + Spring Boot 3.x + Spring Cloud 2023
- MyBatis Plus + MySQL 8.0 + Redis
- Maven 多模块构建

## 项目结构

- `pigx-auth/` - 认证授权服务
- `pigx-gateway/` - 网关服务
- `pigx-upms/` - 用户权限管理
- `pigx-common/` - 公共模块

## 代码规范

- Controller 只做参数校验和结果封装，业务逻辑放 Service
- 统一使用 R 类返回结果
- 异常通过 GlobalExceptionHandler 统一处理

上下文继承机制

Claude Code 的上下文读取规则：

工作目录读取的 CLAUDE.md适用场景
project/根目录 CLAUDE.md跨模块任务、架构设计
project/pigx/pigx/CLAUDE.md后端开发
project/pigx-ui-pro/pigx-ui-pro/CLAUDE.md前端开发
上下文隔离
在子模块目录启动 Claude Code 时，Claude 只会读取该子模块的 CLAUDE.md，不会自动读取父目录的内容。如需跨模块上下文，请在根目录启动。

跨模块业务开发

企业级项目中，一个业务功能往往涉及多个模块的协同修改：

# 示例：新增「用户导出」功能
pigx/
    └── pigx-upms/pigx-upms-biz/       # 后端：导出接口实现
    └── pigx-common/pigx-common-excel/ # 后端：Excel 工具封装
pigx-ui-pro/
    └── src/views/admin/user/          # 前端：导出按钮和交互
pig-docs/
    └── docs/api/upms.md               # 文档：接口说明更新

在根目录启动 Claude Code

跨模块开发时，必须在父仓库根目录启动 Claude Code：

cd pig-cloud
claude

此时 Claude 读取根目录的 CLAUDE.md，能够理解所有模块的位置和职责，可以同时修改多个子模块的代码。

根目录 CLAUDE.md 补充业务模块映射

在根目录 CLAUDE.md 中添加业务功能与代码模块的对应关系：

前后端业务模块映射

业务功能后端模块前端路径文档位置
用户管理pigx/pigx-upms/pigx-ui-pro/src/views/admin/user/pig-docs/docs/api/upms.md
认证授权pigx/pigx-auth/pigx-ui-pro/src/views/login/pig-docs/docs/api/auth.md
代码生成pigx/pigx-codegen/pigx-ui-pro/src/views/gen/pig-docs/docs/api/gen.md

使用并行 Agent 加速开发

对于复杂的跨模块任务，可以让 Claude 派发多个子 Agent 并行工作：

用户：实现用户批量导出功能，需要后端接口、前端按钮、接口文档

Claude 执行：
├── Agent 1 → pigx/pigx-upms/ 编写导出接口
├── Agent 2 → pigx-ui-pro/ 添加导出按钮
└── Agent 3 → pig-docs/ 更新接口文档
根目录启动
跨模块任务必须在根目录启动 Claude Code。在子模块目录启动时，Claude 无法访问其他子模块的代码。
本页目录